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7. Numbers 

Zctalisp includes several types of numbers, with different characteristics. Most numeric 
functions accept any type of numbers as arguments and do the right thing. That is to say, they 
are generic. In Maclisp, there arc generic numeric functions (like plus) and there arc specific 
numeric functions (like + ) which only operate on a certain type of number, but are much more 
efficient. In Zctalisp, this distinction docs not exist; both function names exist for compatibility 
but they are identical. The microprogrammed structure of the machine makes it possible to have 
only the generic functions without loss of efficiency. 



The types of numbers in Zctalisp arc: 



fixnum 



bignum 



Fixnums arc 25-bit twos-complement binary integers. These are the preferred, 
most efficient type of number. 



Bignums arc arbitrary-precision binary integers. 

ratio Ratios represent rational numbers exactly as the quotient of two integers, each of 

which can be a fixnum or a bignum. Ratios with a denominator of one arc not 
normally created, as an integer is returned instead. 

single-float or full-size float 

Full size floats arc floating-point numbers. They have a mantissa of 31 bits and 
an exponent of 11 bits, providing a precision of about 9 digits and a range of 
about 10t300. Stable rounding is employed. 

short-float Short floats are another form of floating-point number, with a mantissa of 17 bits 

and an exponent of 8 bits, providing a precision of about 5 digits and a range of 
about 10f38. Stable rounding is employed. Short floats arc useful because, like 
fixnums, and unlike full-size floats, they don't require any storage. Computing 
with short floats is more efficient than with full-size floats because the operations 
arc faster and consing overhead is eliminated. 

complexnum Complcxnums represent complex numbers with a real part and an imaginary part, 
which can be any type of number except complcxnums. (They must be both 
rational or both floats of the same type). It is impossible to make a complexnum 
whose real part is rational and whose imaginary part is zero; it is always changed 
into a real number. However, it is possible to create complcxnums with an 
imaginary part of 0.0, and such numbers may result from calculations involving 
complcxnums. In fact, 5.0 and 5.0+0.0i arc always distinct; they are not eql, 
and arithmetic operations will never canonicalizc a complexnum with zero 
imaginary part into a real number. 

Generally, Lisp objects have a unique identity; each exists, independent of any other, and 
you can use the eq predicate to determine whether two references are to the same object or not. 
Numbers are the exception to this rule; they don't work this way. The following function may 
return either t or nil. Its behavior is considered undefined; as this manual is written, it returns t 
when interpreted but nil when compiled. 
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(defun foo ( ) 

(let (.(x (float 5))) 

(eq x {car (cons x nil))))) 
This is very strange from the point of view of lisp's usual object semantics, but the 
implementation works this way. in order to gain efficiency, and on the grounds that identity 
testing of numbers is not really an interesting thing to do. So the rule is that the result of 
applying eq to numbers is undefined, and may return either t or nil on what appear to be two 
pointers to the same numeric object. The only reasonable ways to compare numbers arc = (sec 
page 139) and eql (page 69), and other things (equal or equalp) based on them. 

Conversely, fixnums and short floats have the unusual property that they arc always eq if 
they arc equal in value. This is because they do not point to storage: the "pointer" field of a 
fixnum is actually its numeric value, and likewise for short floats. Slylislicly it is better to avoid 
depending on this, by using eql rather than eq. Also, comparing floats of any sort for exact 
equality, even with = which is guaranteed to consider only the numeric values, is usually unwise 
since round-off error can make the answer unpredictable and meaningless. 

The distinction between fixnums and bignums is largely transparent to the user. The user 
simply computes with integers, and the system represents some as fixnums and the rest (less 
efficiently) as bignums. The system automatically converts back and forth between fixnums and 
bignums based solely on the size of the integer. There arc a few low level functions which only 
work on fixnums; this fact is noted in their documentation. Also, when using eq on numbers the 
user needs to be aware of the fixnum/bignum distinction. 

Integer compulations cannot overflow, except for division by zero, since bignums can be of 
arbitrary size. Floating-point computations can get exponent overflow or underflow, if the result is 
too large or small to be represented. Exponent overflow always signals an error. Exponent 
underflow nonnally signals an error, and assumes 0.0 as the answer if the user says to proceed 
from the error. However, if the value of the variable zunderflow is non-nil, the error is skipped 
and computation proceeds with 0.0 in place of the result that was too small. 

When an arithmetic function of more than one argument is given arguments of different 
numeric types, uniform coercion rules are followed to convert the arguments to a common type, 
which is also the type of the result (for functions which return a number). When an integer 
meets a ratio, the result is a ratio. When an integer or ratio meets a float, the result is a float of 
the same sort. When a short-float meets a full-size float, the result is a full-size float. 

If any argument of the arithmetic function is complex, the other arguments are converted to 
complex. The components of a complex result must be both full-size floats, both small-floats, or 
both rational; if they differ, the one whose type comes last in that list is converted to match the 
other. Finally, if the components of the result are rational and the imaginary part is zero, the 
result is simply the real part If, however, the components arc floats, the value is always complex 
even if the imaginary part is zero. 

Thus if the constants in a numerical algorithm are written as short floats (assuming this 
provides adequate precision), and if the input is a short float, the computation is done with short 
floats and the result is a short float, while if the input is a full-size float the computation is done 
in full precision and the result is a full-size float. 



PS:<:E.MAN>FI>NUM.TEXT.36 8-JUN-84 



.isp Machine Manual 137 Numbers 



Xelalisp never automatically converts between full-size floats and short floats in the same way 
as it automatically converts between fixnums and bignums since this would lead cither to 
inefficiency or to unexpected numerical inaccuracies. (When a short float meets a full-size float, 
the result is a full-size float, but if you use only one type, all the results arc of the same type 
too.) This means that a short float computation can get an exponent overflow error even when the 
result could have been represented as a full-size float. 

Floating-point numbers retain only a certain number of bits of precision; therefore, the results 
of computations are only approximate. Full-size floats have 31 bits and short floats have 17 bits, 
not counting the sign. The method of approximation is "stable rounding". The result of an 
arithmetic operation is the float which is closest to the exact value. If the exact result falls 
precisely halfway between two rcprcsentablc floats, the result is rounded down if the least- 
significant bit is 0, or up if the least-significant bit is 1. This choice is arbitrary but insures that 
no systematic bias is introduced. 

Unlike Maclisp, Zctalisp docs not have number declarations in the compiler. Note that 
because fixnums and short floats require no associated storage they arc as efficient as declared 
numbers in Maclisp. Bignums and full-size floats are less efficient; however, bignum and float 
intermediate results arc garbage-collected in a special way that avoids the overhead of the full 
garbage collector. 

The different types of numbers can be distinguished by their printed representations. If a 
number has an exponent separated by 's', it is a short float. If a number has an exponent 
separated by T, it is a full-size float. A leading or embedded (but not trailing) decimal point, 
and/or an exponent separated by 4 e\ indicates a float; which kind is controlled by the variable 
*read-default-float-format*, which is usually set to specify full-size floats. Short floats require a 
special indicator so that naive users will not accidentally compute with the lesser precision. 
Fixnums and bignums have similar printed representations since there is no numerical value that 
has a choice of whether to be a fixnum or a bignum; an integer is a bignum if and only if its 
magnitude is' too big for a fixnum. See the examples on page 518, in the description of what the 
reader understands. 

zunderflow Variable 

When this is nil, floating point exponent underflow is an error. When this is t, exponent 
underflow proceeds, returning zero as the value. The same tiling could be accomplished 
with a condition handler. However, zunderflow is useful for Maclisp compatibility, and 
is also faster. 

sys:float1ng-exponent-overflow (sys.arithmetic-error error) Condition 

sys:float1ng-exponent-underflow (sys.arithmetic-error error) Condition 

sys:floating-exponent-overflow is signaled when the result of an arithmetic operation 
should be a floating point number, but die exponent is too large to be represented in the 
format to be used for the value. sys:floating- exponent- underflow is signaled when the 
exponent is too small. 

The condition instance provides two additional operations; function, which returns the 
arithmetic function that was called, and :small-float-p, which is t if the result was 
supposed to be a short float. 
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sys:floating -exponent-overflow provides the :new-value proceed type. It expects one 
argument, a new value. 

sys:floating-exponent- underflow provides the :use-zero proceed type, which expects no 
argument. 

Unfortunately, it is not possible to make the arguments to the operation available. 
Perhaps someday they will be. 

7.1 Numeric Predicates 

zerop x 

Returns t if x is zero. Otherwise it returns nil. If x is not a number, zerop causes an 
error. For floats, this only returns t for exactly 0.0 or O.OsO. For complex numbers, it 
returns t if both real and imaginary parts arc zero. 

plusp X 

Returns t if its argument is a positive number, strictly greater than zero. Otherwise it 
returns nil. If x is not a number, plusp causes an error. 

mlnusp x 

Returns t if its argument is a negative number, strictly less than zero. Otherwise it 
returns nil. If x is not a number, minusp causes an error. 

oddp number 

Returns t if number is odd, otherwise nil. If number is not a fixnum or a bignum, oddp 
causes an error. 

evenp number 

Returns t if number is even, otherwise nil. If number is not a fixnum or a bignum, 
evenp causes an error. 

slgnp test x Special form 

Tests the sign of a number, signp is present only for Maclisp compatibility and is not 
recommended for use in new programs, signp returns t if x is a number which satisfies 
the lest, nil if it is not a number or docs not meet the test, test is not evaluated, but x 
is. test can be one of the following: 

I x < 

le x < 

e x = 

n x * 

ge x > 

g x>0 



PS:<L.MAN>F1>NUM.TP;XT.36 8-JUN-84 



isp Machine Manual 139 Numeric Comparisons 



Examples: 

(signp ge 12) => t 
(signp le 12) => nil 
(signp n 0) => nil 
(signp g 'foo) => nil 

See also the data-type predicates integerp, rationalp, realp. complexp, floatp, bigp, small - 
floatp, and numberp (page 12). 

7.2 Numeric Comparisons 

All of these functions require that their arguments be numbers; they signal an error if given a 
non-number. Equality tests work on all types of numbers, automatically performing any required 
coercions (as opposed to Maclisp in which generally only the spellcd-out names work for all kinds 
of numbers). Ordering comparisons allow only real numbers, since they arc meaningless on 
complex numbers. 

= &rcst numbers 

Returns t if all the arguments are numerically equal. They need not be of the same type; 
1 and 1.0 are considered equal. Character objects are also allowed, and in effect coerced 
to integers for comparison. 

See also eql, page 69, which insists that both the type and the value match when its 
arguments are numbers. 

> &rcst numbers 

greaterp &rest numbers 

> compares each pair of successive arguments. If any argument is not greater than the 
next, > returns nil. But if the arguments arc monotonically strictly decreasing, the result 
is t. Zero arguments arc always monotonically decreasing, and so is a single argument. 
Examples: 

(>) => t 
(> 3) => t 

' (> 4 3) -> t ■ 
(> 4 3 2 1 0) => t 
(> 4 3 1 2 0) => nil 

greaterp is the Maclisp name for this function. 

>■ &rest numbers 

> &rest numbers 

£ compares each pair of successive arguments. If any argument is less than the next, £ 
returns nil. But if the arguments arc monotonically decreasing or equal, the result is t. 

> = is the Common Lisp name for this function. 
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< &resi numbers 
lessp &rest numbers 

< compares each pair of successive arguments. If any argument is not less than the next, 

< returns nil. Hut if the arguments arc monotonically strictly increasing, the result is t. 
Examples: 

(<) => t 

(< 3) => t 

(< 3 4) => t 

(< 1 1} => nil 

(< 1 2 3 4) => t 

(< 1 3 2 4) => nil 

lessp is the Maclisp name for this function. 

<= &rest numbers 

< &rcst numbers 

< compares its arguments from left to right. If any argument is greater than the next, < 
returns nil. But if the arguments arc monotonically increasing or equal, the result is t. 

< = is the Common Lisp name for this function. 

* &rest numbers 
//= &rcst numbers 

t if no two arguments are numerically equal. This is the same as (not (= ...)) when there 

are two arguments, but not when there arc more than two. 

With zero or one argument, the value is always t, since there is no pair of arguments 
that fail to be equal. 

// = is the Common Lisp name for this function. In Common Lisp syntax, it would be 
written / = . 

max &rcst one-or-more-args 

Returns the largest of its arguments, which must not be complex. 
Example: 

(max 1 3 2) »> 3 
max requires at least one argument. 

m1n &rcst one-or-more-args 

Returns the smallest of its arguments, which must not be complex. 
Example: 

(min 1 3 2) => 1 
min requires at least one argument. 
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7.3 Arithmetic 

All of these functions require that their arguments be numbers, and signal an error if given a 
non-number. They work on all types of numbers, automatically performing any required 
coercions (as opposed to Maclisp, in which generally only the spcllcd-out versions work for all 
kinds of numbers, and the '$' versions are needed for floats). 

+ &rcst args 
plus &rcst args 
+$ &rest args 

Returns the sum of its arguments. If there arc no arguments, it returns 0, which is the 

identity for this operation. 

plus and $+ arc Maclisp names, supported for compatibility. 

- arg &rcst orgs 

-$ arg &rest args 

With only one argument, - returns the negative of its argument. With more than one 
argument, - returns its first argument minus all of the rest of its arguments. 

Examples: 

(- 1) => -1 

(- -3.0) => 3.0 

(- 3 1) => 2 

(- 9 2 1) => 6 

-$ is a Maclisp name, supported for compatibility. 

minus x 

Returns the negative of x, just like - with one argument. 

difference arg &rcst args 

Returns its first argument minus all of the rest of its arguments. If there are at least two 
arguments, difference is equivalent to -. 

abs x 

Returns \x\, the absolute value of the number x. abs for real numbers could have been 
defined as 

(defun abs (x) 

(cond ((minusp x) (minus x)) 
(t x))) 

abs of a complex number could be computed, though imprecisely, as 
(sqrt (* (realpart x) 2) (* (imagpart x) 2)) 
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* &resi args 
times &rcst args 
*$ &rest args 

Returns the product of its arguments. If there are no arguments, it returns 1, which is 

the identity for this operation. 

times and *$ arc Maclisp names, supported for compatibility. 

// arg &rest args 

//$ urg &rcst args 

With more than one argument, // it returns the first argument divided by all of the rest 
of its arguments. With only one argument, (// x) is the same as (// 1 .v). 

The name of this function is written // rather than / because / is the escape character in 
traditional Lisp syntax and must be escaped in order to suppress that significance. //$ is 
a Maclisp name, supported for compatibility. 

// of two integers returns an integer even if the mathematically correct value is not an 
integer. More precisely, die value is the same as the first value returned by truncate (see 
below). This will eventually be changed, and then the value will be a ratio if necessary 
so that the it is mathematically correct. All code that relics on // to return an integer 
value rather than a ratio should be converted to use truncate (or floor or ceiling, which 
may simplify the code further). In the mean time, use the function cli:// if you want a 
rational result. 

Examples: 

(// 3 2) => 1 ;Fixnum division truncates. 

(// 3 -2) => -1 

(// -3 2) *> -1 

(// -3 -2) => 1 

(7/ 3 2.0) => 1.5 

(// 3 2.0s0) => 1.5s0 

(// 4 2) *> 2 

(// 12. 2. 3.) => 2 

(// 4.0) => .25 

quotient arg &rest args 

Returns the first argument divided by all of the rest of its arguments. When there are 
two or more arguments, quotient is equivalent to //. 

cl1:// number &rest numbers 

This is the Common Lisp division function. It is like // except that it uses exact rational 
division when the arguments are integers. 

// will someday be changed to divide integers exactly. Then there will no longer be a 
distinct function cli://; that name will become equivalent to //. 
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Note that in Common Lisp syntax yoir would write just / rather than cli://. 

There arc four functions for "integer division", the sort which produces a quotient and a 
remainder. They differ in how they round the quotient to an integer, and therefore also in the 
sign of the remainder. The arguments must be real, since ordering is needed to compute the 
value. The quotient is always an integer, but the arguments and remainder need not be. 

floor v &optional 0'1) 

floor's first value is the largest integer less than or equal to the quotient of x divided by 
)'• ■ 

The second value is the remainder, x minus y times the first value. This has the same 
sign as ;• (or may be zero), regardless of the sign of x. 

With one argument, floor's first value is the largest integer less than or equal to the 
argument. 

celling * Aoptional 0'1) 

ceiling's first value is the smallest integer greater than or equal to the quotient of x 
divided by y. 

The second value is the remainder, x minus y times the first value. This has the opposite 
sign from ;- (or may be zero), regardless of die sign of x. 

With one argument, ceiling's first value is the smallest integer greater than or equal to 
the argument. 

truncate x &optional (y1) 

truncate is the same as floor if die arguments have die same sign, ceiling if they have 
opposite signs, truncate is the function diat die divide instruction on most computers 
implements. 

truncate's first value is the nearest integer, in the direction of zero, to die quotient of x 
divided by y. 

The second value is the remainder, x minus y times the first value. This has the same 
sign as x (or may be zero). 

round x &optional (y1) 

round's first value is die nearest integer to the quotient of x divided by y. If the 
quotient is midway between two integers, die even integer of the two is used. 

The second value is the remainder, x minus y times the first value. The sign of this 
remainder cannot be predicted from the signs of the arguments alone. 

With one argument, round's first value is die integer nearest to the argument. 

Here is a table which clarifies the meaning of floor, ceiling, truncate and round with one 
argument: 
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floor 


cei 1 ing 


truncate 


rou 


2.6 


2 


3 


2 


3 


2.5 


2 


3 


2 


2 


2.4 


2 


3 


2 


2 


0.7 





1 





1 


0.3 





1 








0.3 


-1 











0.7 


-1 








-1 


2.4 


-3 


-2 


-2 


-2 


2.5 


-3 


-2 


-2 


-2 


2.5 


-3 


-2 


-2 


-2 


2.6 


-3 


-2 


-2 


-3 



There arc two kinds of remainder function, which differ in the treatment of negative numbers. 
The remainder can also be obtained as the second value of one of the integer division functions 
above, but if only the remainedcr is desired it is simpler to use these functions. 

\ x y 

remainder x y 
cl 1 :rem x y 

Returns the remainder of x divided by y. x and y must be integers (fixnums or 
bignums). This is the same as the second value of (truncate x y). Only the absolute 
value of the divisor is relevant. 

(\ 3 2) => 1 

(\ -3 2) => -1 

(\ 3 -2) => 1 

(\ -3 -2) => -1 

Common Lisp gives this function the name rem, but since rem in traditional Zctalisp is a 
ainction to remove elements from lists (sec page 105), the name rem is defined to mean 
remainder only in Common Lisp programs. Note that the name \ would have to be 
written as \\ in Common Lisp syntax; but the function \ is not standard Common Lisp. 

mod number divisor 

Returns the root of number modulo divisor. This is a number between and divisor, or 
possibly 0, whose difference from number is a multiple of divisor. It is the same as the 
second value of (floor number divisor). Examples: 

(mod 2 5) => 2 

(mod -2 5) => 3 

(mod -2 -5) *> -2 

(mod 2 -5) => -3 

There arc four "floating point integer division" functions. These produce a result which is a 
floating point number whose value is exactly integral. 
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f floor .v &optional 0'1) 

fcelUng v &optionul 0'1) 

f truncate x &optional 0' "0 

f round v &optional (yl) 

Like floor, ceiling, truncate and round except that the first value is converted from an 
integer to a float. If .x is a float, then the result is the same type of float as x. 

sys:d1v1de-by-zero (sys:arithmetic- error error) Condition 

Dividing by zero, using any of the above division functions, signals this condition. The 
function operation on the condition instance returns the name of the division function. 
The :dividend operation may be available to return the number that was divided. 

1+ x 
addl x 

1+$ x 

(1 + x) is the same as ( + x 1). The other two names arc for Maclisp compatibility. 

1- x 
subl x 
1-$ x 

(1- x) is the same as (- x 1). Note that the short name may be confusing: (1- x) docs 
not mean 1-jr; rather, it means x-l. The names subl and 1-$ are for Maclisp 
compatibility. 

gcd &rest integers 

\\ &rest integers 

Returns the greatest common divisor of all its arguments, which must be integers. With 
one argument, the value is that argument. With no arguments, the value is zero. 

In Common Lisp syntax \\ would be written as WW, but only the name gcd is valid in 
strict Common Lisp. 

1cm integer &rest more-integers 

Returns the least common multiple of the specified integers. 

expt x y 

* x y 

A $ x y 

Returns x raised to the /th power. The result is rational (and possibly an integer) if x is 
rational and y an integer. If the exponent is an integer a repeated-squaring algorithm is 
used; otherwise the result is (exp (* y (log x))). 

If y is zero, the result is (+ 1 (* x >-)); this is equal to one, but its type depends on 
those of x and y. 
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sys:zero-to-negat1ve power (sys:arithmetic- error error) Condition 

This condition is signaled when expt's first iirgument is zero and the second argument is 
negative. 

sqrt x 

Returns the square root of x. A mathematically unavoidable discontinuity occurs for 
negative real arguments, for which the value returned is a positive real times i. 

(sqrt 4) => 2 

(sqrt -4) => 0+2i 

(sqrt -4+.000H) => . 00005 + 2 i (approximately) 

(sqrt -4-.0001i) => .00005-2i (approximately) 

1sqrt x 

Integer square-root, x must be an integer; the result is the greatest integer less than or 

equal to the exact square root of x. 

*d1f x y 
•plus x y 
•quo x y 
•times x y 

These are the internal microcoded arithmetic functions. There is no reason why anyone 
should need to write code with these explicitly, since the compiler knows how to generate 
the appropriate code for plus, +, etc. These names arc only here for Maclisp 
compatibility. 

%d1v dividend divisor 

The internal division function used by cli://, it was available before cli:// was and may 
therefore be used in some programs. It takes exactly two arguments. Uses of %div 
should be changed to use cli://. 

7.4 Complex Number Functions 

See also the predicates realp and complexp (page 12). 

complex x &optional y 

Returns the complex number whose real part is x and whose imaginary part is y. 

If x is rational and >' is zero or omitted, the value is x, and not a complex number at 
all. If x is a float and y is zero or omitted, of if y is a floating zero, the result is a 
complcxnum whose imaginary part is zero. 

realpart z 

Returns the real part of the number z. If z is real, this is the same as z. 
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Imagpart z 

Returns the imaginary part of the number z. If z is real, this is /cm. 

conjugate z 

Returns the complex conjugate of the number z. If z is real, this is the same as z. 

phase z 

Returns the phase angle of the complex number z in its polar form. This is the angle 
from the positive .v axis to the ray from the origin through z. The value is always in the 
interval (-it, it]. 

(phase -4) => m 

(phase --4- . OOOli ) is just over -m. 

(phase 0) => (an arbitrary choice) 

ds angle 

Returns the complex number of unit magnitude whose phase is angle. This is equal to 
(complex (cos angle) (sin angle)), angle must be real. 

slgnum z 

Returns a number with unit magnitude and the same type and phase as z. if z is zero, 
the value is zero. 

If z is real, the value is = to 1 or -1; it may be a float, however. 

7.5 Transcendental Functions 

These functions arc only for floating-point arguments; if given an integer they convert it to a 
float. If given a short float, they return a short float. 

P"! Constant 

The value of w, as a full-size float 

exp x 

Returns e raised to the x'th power, where e is the base of natural logarithms. 

log x &optional base 

Returns the logarithm of x to base base, base defaults to e. When base is e, the 
imaginary part of the value is in die interval (-it, m]\ for negative real x, the value has 
imaginary part w. 

If base is specified, the result is 

(// (log x) (log base)) 

sys: zero- log (sys:arithmetic- error error) Condition 

This is signaled when the argument to log is zero. 
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sin .if 

COS X 

tan x 

Return, respectively, the sine, cosine and tangent of x, where .v is expressed in radians. 
x may be complex. 

slnd x 
cosd x 
tand x 

Return, respectively, the sine, cosine and tangent of x, where x is expressed in degrees. 

asln x 
acos x 

Returns the angle (in radians) whose sine (respectively, cosine) is v. The real part of the 
result of asin is between -w/2 and it/2; acos and asin of any given argument always 
add up to tj/2. 

atan y &optional x 

If only y is given, the value is the angle, in radians, whose tangent is y. The real part 
of the result is between zero and -it. 

If x is also given, both arguments must be real, and the value is an angle, in radians, 
whose tangent is y/x. However, the signs of the two arguments are used to choose 
between two angles which differ by -n and have the same tangent. The one chosen is the 
angle from the x-axis counterclockwise to the line from the origin to the point (*, y). 

atan always returns a non-negative number between zero and 2w. 

atan2 y &optional x 

c1'1:atan ; ; &optional x 

Like atan but always returns a value whose real part is between -n/2 and w/2. The 
value is cither the same as the value of atan or differs from it by it. 

atan2 is the traditional name of this function. In Common Lisp it is called atan; it is 
documented as cli:atan since die name atan has a different meaning in traditional syntax. 

slnh jc 
cosh x 
tanh x 
aslnh x 
acosh x 
atanh x 

The hyperbolic and inverse hyperbolic functions. 
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7.6 Numeric Type Conversions 

These functions arc provided to allow specific conversions of data types to be forced, when 
desired. 

float number &optional float 

Converts number to a floating point number and returns it. 

\f float is specified, the result is of the same floating point format as float. If number is a 
float of a different format then it is converted. 

If float is omitted, then number is converted to a single-float unless it is already a floating 
point number. 

A complex number is converted to one whose real and imaginary parts arc full-size floats 
unless they arc already both floats. 

small-float x 
short-float x 

Converts any kind of real number to a short-float. A complex number is converted to 
one whose real and imaginary parts arc short floats. The two names are synonymous. 

numerator x 

Returns the numerator of the rational number jc. If x is an integer, the value equals x. 
If x is not an integer or ratio, an error is signaled. 

denominator x 

Returns the denominator of the rational number x. If x is an integer, the value is 1. If 
x is not an integer or ratio, an error is signaled. 

rational x 

Converts jc to a rational number. If x is an integer or a ratio, it is returned unchanged. 
If it is a floating point number, it is regarded as an exact fraction whose numerator is the 
mantissa and whose denominator is a power of two. For any other argument, an error is 
signaled. 

rationalize x &optional precision 

Returns a rational approximation to jc. 

If there is only one argument, and it is an integer or a ratio, it is returned unchanged. 
If die argument is a floating point number, a rational number is returned which, if 
converted to a floating point number, would produce the original argument. Of all such 
rational numbers, the one chosen has the smallest numerator and denominator. 

If there arc two arguments, the second one specifics how much precision of the first 
argument should be considered significant, precision can be a positive integer (the number 
of bits to use), a negative integer (the number of bits to drop at the end), or a floating 
point number (minus its exponent is the number of bits to use). 
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If .there arc two arguments and the first is rational, the value is a "simpler"' rational which 
approximates it. 

fix Jf 

Converts .v from a float or ratio to an integer, truncating towards negative infinity. The 
result is a fixnum or a bignum as appropriate. If x is already a fixnum or a bignum, it is 
returned unchanged. 

fix is the same as floor except that floor returns an additional value, fix is semi-obsolete, 
since the functions floor, ceiling, truncate and round provide four different ways of 
converting numbers to integers with different kinds of rounding. 

flxr x 

fixr is the same as round except that round returns an additional value, fixr is considered 
obsolete. 

7.7 Floating Point Numbers 

decode- float float 

Returns three values which describe the value of float. 

The first value is a positive float of the same format having the same mantissa, but with 
an exponent chosen to make it between 1/2 and 1, less than 1. 

The second value is the exponent of float: the power of 2 by which the first value needs 
to be scaled in order to get float back. 

The third value expresses die sign of float. It is a float of the same format as float, 
whose value is either 1 or -1. Example: 
(decode-float 38.2) 

=> 0.598875 6 1.0 

1nteger-decode-float float 

Like decode-float except that the first value is scaled so as to make it an integer, and 
the second value is modified by addition of a constant to compensate. 
( integer-decode-f loat 38.2) 

=> #011431463146 -25. 1.0 

scale-float float integer 

Multiplies float by 2 raised to the integer power, float can actually be an integer also; it 
is converted to a float and then scaled. 

(scale-float 0.596875 6) => 38.2 

(scale-float #011431463146 -25.) => 38.2 
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float-sign flout I &optional float 2 

Returns a float whose sign matches that of float I and whose magnitude and format are 
those o{ float 2. If float 2 is omitted, 1.0 is used as the magnitude and float! 's format is 
used. 

(float-sign -l.OsO 35.3) => -35.3 

(float-sign -l.OsO 35.3s0) => -35.3s0 

float- radix float 

Defined by Common Lisp to return the radix used for the exponent in the format used 
for float. On the Lisp Machine, floating point exponents are always powers of 2, so 
float -radix ignores its argument and always returns 2. 

float-digits float 

Returns the number of bits of mantissa in the floating point format which float is an 
example of. It is 17 for short floats and 31 for full size ones. 

float- precision float 

Returns the number of significant figures present in in die mantissa of float. This is 
always the same as (float -digits float) for normalized numbers, and on the Lisp Machine 
all floats arc normalized, so the two functions arc the same. 

7.8 Logical Operations on Numbers 

Except for Ish and rot, these functions operate on both fixnums and bignums. Ish and rot 
have an inherent word-length limitation and hence only operate on 25-bit fixnums. Negative 
numbers arc operated on in their 2Vcomplemcnt representation. 

loglor &rest integers 

Returns the bit-wise logical inclusive or of its arguments. With no arguments, the value is 
zero, which is the identity for this operation. 
Example (in octal): 

(logior #o4002 #o67) => #o4067 

logand &rcst integers 

Returns the bit-wise logical and of its arguments. With no arguments, the value is -1, 
which is the identity for this operation. 
Examples (in octal): 

(logand #o3456 #o707) => #o406 

(logand #o3456 #o-100) => #o3400 

logxor &rest integers 

Returns the bit-wise logical exclusive or of its arguments. With no arguments, the value is 
zero, which is the identity for this operation. 
Example (in octal): 

(logxor #02531 #07777) => #05246 
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logeqv &rest integers 

Combines the integers together bitwise using the equivalence operation, which, for two 

arguments, is defined to result in 1 if the two argument bits are equal. This operation is 

asociativc. Willi no args, the value is -1, which is an identity for the equivalence 

operation. 

I Ixample (in octal): 

(logeqv #o2531 #o7707) => #0-5237 = ...77772541 

Non-associative bitwise operations lake only two arguments: 

lognand integer I integer 2 

Returns the bitwise-nand of the two arguments. A bit of the result is 1 if at least one of 
the corresponding argument bits is 0. 

1 o g n o r integer I integer} 

Returns the bilwisc-nor of the two arguments. A bit of the result is 1 if both of the 
corresponding argument bits are 0. 

1 o g o r c 1 integer] integer2 

Returns the bitwisc-or of integer2 with the complement of integer!. 

logorcZ integer! integer2 

Returns the bitwisc-or of integer! with the complement of in(eger2. 

log an del integer! integer2 

Returns the bitwisc-and of integer2 with the complement of integer!. 

logandc2 integer! integer2 

Returns the bitwisc-and of integer! with the complement of integer2. 

lognot number 

Returns the logical complement of number. This is the same as logxor'ing number with 

-1. 
Example: 

(lognot #03456) => #0-3457 

boole fn &rest one-or-more-args 

boole is the generalization of logand, logior, and logxor. //; should be a fixnum 
between and 17 octal inclusive; it controls the function which is computed. If the 
binary representation of //; is abed (a is the most significant bit, d the least) then the truth 
table for the Boolean operation is as follows: 

y 
I o 1 



0| a c 

x I 

1| b d 
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If boole has more than three arguments, it is associated left to right; thus, 

(boole fn x y z) = (boole fn (boole fn x y) z) 
With two arguments, the result of boole is simply its second argument. At least two 
arguments arc required. 



Examples: 

(boole 1 x y) 

(boole 6 x y) 

(boole 2 x y) 



(logand x y) 
( logxor x y ) 
(logand (lognot x) y) 



logand, logior, and so on are usually preferred over the equivalent forms of boole. 

boole is useful when the operation to be performed is not constant. 

boole- lor Constant 

boole-and Constant 

boole-xor Constant 

boole -eqv Constant 

boole-nand Constant 

boole-nor Constant 

boole-orcl Constant 

boole-orc2 Constant 

boole- an del Constant 

boole-andc2 Constant 
The boole opcodes that correspond to the functions logior, logand, etc. 



boole-clr 
boole- set 
boole-1 
boole-2 

The boole opcodes for the four trivial operations. 



Constant 
Constant 
Constant 
Constant 
Respectively, they arc those which 



always return zero, always return one, always return the first argument, and always return 
the second argument. 

bit-test x y 

logtest x y 

bit-test is a predicate which returns t if any of the bits designated by the l's in x are l's 
in >-. bit-test is implemented as a macro which expands as follows: 
(bit-test jc >•) ==> (not (zerop ( logand x y)) ) 
logtest is the Common Lisp name for this function. 



Ish x y 



Returns x shifted left y bits if y is positive or zero, or x shifted right |>>| bits if y is 
negative. Zero bits arc shifted in (at cither end) to fill unused positions, x and y must 
be fixnums. (In some applications you may find ash useful for shifting bignums; see 
below.) 
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I Examples: 

(lsh 4 1) => #ol0 

(lsh #ol4 -2) => 3 

(lsh -1 1) => -2 

ash .if y 

Shifts .v arithmetically left y bits if v is positive, or right -;- bits if y is negative. Unused 
positions are filled by zeroes from the right, and by copies of the sign bit from the left. 
Thus, unlike lsh. the sign of the result is always the same as the sign of .v. If .* is a 
fixnum or a bignum. this is a shifting operation. If .v is a float, this docs scaling 
(multiplication by a power of two), rather than actually shifting any bits. 

rot x y 

Returns x rotated left y bits if y is positive or zero, or .v rotated right |v| bits if y is 
negative. The rotation considers x as a 25-bit number (unlike Maclisp, which considers x 
to be a 36-bit number in both the pdp-10 and Multics implementations), x and y must 
be fixnums. (There is no function for rotating bignums.) 
Examples: 

(rot 1 2) => 4 

(rot 1 -2) => #020000000 

(rot -1 7) => -1 

(rot #ol5 25. ) => #ol5 

logcount integer 

Returns the number of 1 bits in integer, if it is positive. Returns the number of bits in 
integer, if it is negative. (There arc infinitely many 1 bits in a negative integer.) 

(logcount #ol5) => 3 

(logcount #o-15) => 2 

Integer- length integer 

The minimum number of bits (aside from sign) needed to represent integer in two's 
complement. This is the same as haulong for positive numbers. 

(integer-length 0) => 

(integer-length 7) => 3 

(integer-length 8) => 4 

(integer-length -7) => 3 

(integer-length -8) => 3 

(integer-length -9) *> 4 

haulong integer 

The same as integer- length of the absolute value of integer. This name exists for 
Maclisp compatibility only. 

halpart x n 

Returns the high n bits of die binary representation of \x\, or the low -n bits if n is 
negative, x may be a fixnum or a bignum; its sign is ignored, haipart could have been 
defined by: 



PS:<I..MAN>FI>NUM.TEXT.36 8-JUN-84 



isp Machine Manual 155 liyic Manipulation Functions 



(defun haipart (x n) 
(setq x (abs x)) 
(if (minusp n) 

(logand x (1- (ash 1 (- n)))) 

(ash x (min (- n (haulong x)) 

0)))) 

7.9 Byte Manipulation Functions 

Several functions are provided for dealing with an arbitrary-width field of contiguous bits 
appearing anywhere in an integer (a fixmim or a bignum). Such a contiguous set of bits is called 
a byte. Note that we arc not using the term byte to mean eight bits, but rather any number of 
bits within a number. These functions use numbers called byte specifiers to 

designate a specific byte position within any word. A byte specifier contains two pieces of 
information: the size of the byte, and the position of the byte. The position is expressed as the 
number of least significant bits which arc not included in the byte. A position of zero means that 
the byte is at the right (least significant) end of the number. 

The maximum value of the size is 24, since a byte must fit in a fixmim although bytes can 
be loaded from and deposited into bignums. (Bytes are always positive numbers.) 

Byte specifiers arc represented as fixnums whose two lowest octal digits represent the size of 
die byte, and whose higher (usually two, but sometimes more) octal digits represent the position 
of the byte within a number. For example, the byte-specifier #o00T0 (i.e. 10 octal) refers to the 
lowest eight bits of a word, and the byte-specifier #ol010 refers to the next eight bits. The 
format of byte-specifiers is taken from the pdp-10 byte instructions. 

Much old code contains byte specifiers written explicitly as octal numbers. It is cleaner to 
construct byte specifiers using byte instead. Decomposition of byte specifiers should always be 
done with byte-position and byte-size, as at some time in the future other kinds of byte 
specifiers may be created to refer to fields whose size is greater than #o77. 

byte size position 

Returns a byte specifier for the byte of size bits, positioned to exclude the position least 
significant bits. This byte specifier can be passed as the first argument to Idb, dpb, 
%logldb, %logdpb, mask-field, %p-ldb, %p- Idb -offset, and so on. 

byte-pos1t1on byte-spec 
byte-size byte- spec 

Return, respectively, the size and the position of byte-spec. It is always true that 
(byte (byte-size byte-spec) (byte-position byte-spec)) 

equals byte-spec. 

Idb byte-spec integer 

Extracts a byte from integer according to byte-soec. The contents of this byte arc returned 
right-justified in a fixnum. The name of the function, Idb, means 'load byte', integer 
may be a fixnum or a bignum. The returned value is always a fixnum. 
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Example: 

(Idb (byte 6 3} #o45G7) => #o56 

Toad-byte integer position size 

This is like Idb except that instead of using a byte specifier, the position and size arc 
passed as separate arguments. The argument order is not analogous to that of Idb so that 
load -byte can be compatible with Maclisp. 

Idb-test byte- spec integer 

Idb-test is a predicate which returns t if any of the bits designated by the byte specifier 
byte-spec are l's in integer. That is, it returns t if the designated field is non-zero. Idb- 
test is implemented as a macro which expands as follows: 

(Idb-test byte-spec integer) = = > (not (zerop (Idb byte-spec integer))) 

logbltp index integer 

t if the bit index up from the least significant in integer is a 1. This is equivalent to 
(Idb-test (byte index 1) integer). 

mask-field byte- spec fixnum 

This is similar to Idb: however, the specified byte of fixnum is positioned in the same 
byte of the returned value. The returned value is zero outside of -that byte, fixnum must 
be a fixnum. 
Example: 

(mask-field (byte 6 3) #04567) => #o560 

dpb byte] byte-spec\ integer \ 

Returns a number which is the same as integer except in the bits specified by byte-spec. 
The low bits of byte, appropriately many, are placed in those bits, byte is interpreted as 
being right-justified, as if it were the result of Idb. integer may be a fixnum or a bignum. 
The name means 'deposit byte'. 
Example: 

(dpb #o23 (byte 6 3) #04567) => #04237 

deposit- byte integer position size byte 

This is like dpb except that instead of using a byte specifier, the position and size are 
passed as separate arguments. The argument order is not analogous to that of dpb so that 
deposit-byte can be compatible with Maclisp. 

deposit-field byte byte-spec fixnum 

ITiis is like dpb, except that byte is not taken to be left-justified; the byte-spec bits of 
byte are used for the byte-spec bits of the result, with the rest of the bits taken from 
fixnum. fixnum must be a fixnum. 
Example: 

(deposit-field #o230 (byte 6 3) #04567) => #04237 

The behavior of the following two functions depends on the size of fixnums, and so functions 
using them may not work the same way on future implementations of Zetalisp. Their names start 
with % because they arc more like machine- level subprimitives than the previous functions. 
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%logldb byte- spec fixnum 

%logldb is like Idb except that it only loads out of fixnums and allows a byte size of 25, 
i.e. all 25 bits of the fixnum including the sign bit. 

%logdpb byte byte-spec fixnum 

%logdpb is like dpb except that it only deposits into fixnums. Using this to change the 
sign-bit leaves the result as a fixnum, while dpb would produce a bignum result for 
arithmetic correctness. %logdpb is good for manipulating fixnum bit-masks such as arc 
used in some internal system tables and data-structures. 

7.10 Random Numbers 

The functions in this section provide a pseudo-random number generator facility. The basic 
function you use is random, which returns a new pscudo- random number each time it is called. 

random &optional number random-state 

Returns a randomly generated number. If number is specified, the random number is of 
die same type as number (floating if number is floating, etc.), nonnegative, and less than 
number. 

If number is omitted, the result is a randomly chosen fixnum, with all fixnums being 
equally likely. 

If random-state is present, it is used and updated in generating the random number. 
Otherwise, die default random-state (the value of * random -state*) is used (and is created 
if it doesn't already exist). The algorithm is executed inside a without-interrupts (see 
page 684) so two processes can use the same random-state without colliding. 

s1: random- In -range low high 

Returns a random float in the interval [low, high). The default random-state is used. 

A random-state is a named structure of type random -state whose contents control the future 
actions of .the random number generator. Each time you call the function random, it uses (and 
updates) one random-state. One random-state exists standardly and is used by default. To have 
several different controllable, rcscttable sources of random numbers, you can create your own 
random-states. Random-states print as 

#s( random-state . . .more data. . . ) 
so that they can be read back in. 

random-state -p object 

t if object is a random-state. 

♦random-state* Variable 

This random-state is used by default when random is called and the random-state is not 
explicitly specified. 
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make- random- state ^optional random-state 

Crciitcs and returns a new random-state object. If random- state is nil, the new random- 
state is a copy of "random -state*. If random-state is a random-state, the new one is a 
copy of that one. If random-slate is t. the new random-state is initialized truly randomly 
(based on the value of (time)). 

A random-state actually consists of an array of numbers and two pointers into the array. The 
pointers circulate around the array; each time a random number is requested, both pointers are 
advanced by one, wrapping around at the end of the array. Thus, the distance forward from the 
first pointer to the second pointer stays the same, allowing for wraparound. Let the length of the 
array be length and the distance between the pointers be offset. To generate a new random 
number, each pointer is set to its old value plus one, modulo length. Then the two elements of 
the array addressed by the pointers arc added together; the sum is stored back into the array at 
the location where the second pointer points, and is returned as the random number after being 
normalized into the right range. 

This algorithm produces well-distributed random numbers if length and offset arc chosen 
carefully, so that the polynomial x A length + x ~ offset + 1 is irreducible over the mod-2 
integers. The system uses 71. and 35. 

The contents of the array of numbers should be initialized to anything moderately random, to 
make the algorithm work. The contents get initialized by a simple random number generator, 
based on a number called the seed. The initial value of the seed is set when the random-state is 
created, and it can be changed. 

si : random-create-array length offset seed &optional (am/ nil) 

Creates and returns a new random-state according to precise specifications, length is the 
length of the array, offset is the distance between the pointers and should be an integer 
less than length, seed is the initial value of the seed, and should be a fixnum. This calls 
si:random-initialize on the random state before returning it. 

s 1 : random- Initialize random-state &optional new-seed 

random-state must be a random-state, such as is created by si:random-create-array, If 
newsced is provided, it should be a fixnum, and the seed is set to it. si:random- 
initialize reinitializes the contents of the array from the seed (calling random changes the 
contents of the array and the pointers, but not the seed). 

7.11 Information on Numeric Precision 

Common Lisp defines some constants whose values give information in a standard way about 
the ranges of numbers reprcscntablc in the individual Lisp implementation. 

most-negat1ve-f1xnum Constant 

Any integer smaller than this must be a bignum. 
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most-pos1t1ve-f 1xnum 

Any integer larger than this must be a bignum. 

most- positive-short- float 

No short float- can be greater than this number. 

least- positive -short-float 

No positive short float can be closer to zero than this number. 

least- negative- short-float 

No negative short float can be closer to zero than this number. 

most -negative -short- float 

No short float can be less than this (negative) number. 

most-positive -single-float 
least-positive- single-float 
least- negative-single- float 
most-negat1ve-s Ingle-float 

Similar to the above, but for full-size floats rather than for short floats. 

most-pos1t1ve-double-f1oat 
least-positive-double-float 
least- negative-double-float 
most-negative -double-float 
most-positive- long-float 
least-positive -long-float 
least- negative- long- float 
most-negative- long-float 



Constant 



Constant 



Constant 



Constant 



Constant 



Constant 
Constant 
Constant 
Constant 



Constant 
Constant 
Constant 
Constant 
Constant 
Constant 
Constant 
Constant 



These arc defined by Common Lisp to be similar to the above, but for double-floats and 
long-floats. On the Lisp Machine, there are no distinct double and long floating formats; 
they are synonyms for single-floats. So these constants exist but their values are the same 
as those of most-positive-single-float and so on. 

short-float-epsllon Constant 

Smallest positive short float which can be added to l.OsO and make a difference. That is, 
for any short float x less than this, (+ 1.0s0 x) equals l.OsO. 



s1ngle-float-eps1lon 
double-f loat-epsilon 
long-float-epsllon 

Smallest positive float which can be added to 1.0 and make a difference, 
arc synonyms on the Lisp Machine, for reasons explained above. 



Constant 
Constant 
Constant 
The three names 



short-float-negat1ve-eps1lon Constant 

Smallest positive short float which can be subtracted from l.OsO and make a difference. 
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s1ngle-float-negative-eps1lon Constant 

double-float-negatlve-epsllon Constant 

long-float-negatlve-epsHon Constant 

Smallest positive float which can be subtracted from 1.0 and make a difference. 

7.12 Arithmetic Ignoring Overflow 

Sometimes it is desirable to have a form of arithmetic which has no overflow checking (that 
would produce bignums), and truncates results to the word size of the machine. 

%po1n tar-plus pointer-/ pointer 2 

Returns a fixnum which is pointer-/ plus pointer- J, modulo what could be stored in the 
size of the pointer field (currently 25 bits). Arguments other than fixnums arc rarely 
useful, but no type checks arc made. 

%po1nter-d1fference pointer-/ pointer-2 

Returns a fixnum which is pointer-/ minus pointer-2. If the arguments are fixnums, rather 
man true pointers, this provides subtraction modulo what can be stored in the pointer 
field. 

%po1nt.er-t1mes pointer- 1 pointer-2 

Returns a fixnum which is pointer- 1 times, pointer-2. Arguments other than fixnums are 
rarely useful, but no type checks are made. The two pointer fields are regarded as signed 
numbers. 

7.13 24-Bit Arithmetic 

Sometimes it is useful to have a form of truncating arithmetic with a strictly specified field 
width which is independent of the range of fixnums permissible on a particular machine. In 
Zetalisp, this is provided by the following set of functions. Their answers are correct only modulo 
2t24. 

These ftmctions should not be used for efficiency; they arc probably less efficient than the 
functions which do check for overflow. They arc intended for algorithms which require this sort 
of arithmetic, such as hash functions and pseudo- random number generation. 

%24-bIt-plus x y 

Returns the sum of x and y modulo 2t24. Both arguments must be fixnums. 

%24-blt-d1fference x y 

Returns the difference of x and y modulo 2t24. Both arguments must be fixnums. 

%24-blt-t1mes x y 

Returns the product of x and y modulo 2t24. Both arguments must be fixnums. 
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7.14 Double-Precision Arithmetic 

These peculiar functions arc useful in programs that don't want to use bignums for one reason 
or another. They should usually be avoided, as they arc difficult to use and understand, and they 
depend on special numbers of bits and on the use of twos-complement notation. 

A double-precision number has 50 bits, of which one is the sign bit. It is represented as two 
fixiuinis. The less signficant fixniim conveys 25 signficant bits and is regarded as unsigned (that is, 
what is normally the sign bit is treated as an ordinary data bit); the more significant fixnum has 
the same sign as the double-precision number. Only %float-double handles negative double- 
precision numbers; for the other functions, the more signficant fixnum is always positive and 
contains only 24 bits of actual data. 

%mult1ply-f pactions numl num2 

Returns bits 25 through 48 (the most significant half) of the product of numl and num2, 
regarded as unsigned integers. If you call this and %pointer- times on the same 
arguments numl and num2, you can combine the results into a double-precision product. 
If numl and numl arc regarded as two's-complcmcnt fractions, -1 < num < 1, %multiply- 
fractions returns 1/2 of their correct product as a fraction. 

[The name of this function isn't too great.] 

%d1v1de-double dividend! 25: 48] dividend[0:24] divisor 

Divides the double-precision number given by the first two arguments by the third 
argument, and returns the single-precision quotient. Causes an error if divisor is zero or if 
the quotient won't fit in single precision. 

There are only 24 bits in each half of the number, as neither sign bit is used to convey 
information. 

%rema1nder-double dividend[25:48] dividend[0:24] divisor 

Divides the double-precision number given by the first two arguments by the third 
argument, and returns the remainder. Causes an error if divisor is zero. 

%fl oat-double high25 low25 

high25 and low25, which must be fixnums, are concatenated to produce a 50-bit unsigned 
positive integer. A full-size float containing the same value is constructed and returned. 
Note that only the 31 most significant bits are retained (after removal of leading zeroes.) 
This function is mainly for the benefit of read. 
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